SGI Freeware 1998 November/Freeware November 1998.img/dist/fw_elisp-manual-19.idb/usr/freeware/info/elisp-7.z/elisp-7

GNU Info File | 1998-05-26 | 46KB | 899 lines

This is Info file elisp, produced by Makeinfo-1.63 from the input file
elisp.texi.
   This version is the edition 2.4.2 of the GNU Emacs Lisp Reference
Manual.  It corresponds to Emacs Version 19.34.
   Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA  02111-1307  USA
   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software
Foundation, Inc.
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.
File: elisp,  Node: Eval,  Next: Forms,  Prev: Intro Eval,  Up: Evaluation
   Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run.  On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list.  On these occasions, use the `eval' function.
   *Note:* it is generally cleaner and more flexible to call functions
that are stored in data structures, rather than to evaluate expressions
stored in data structures.  Using functions provides the ability to
pass information to them as arguments.
   The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
values.  Loading a file also does evaluation (*note Loading::.).
 - Function: eval FORM
     This is the basic function for performing evaluation.  It evaluates
     FORM in the current environment and returns the result.  How the
     evaluation proceeds depends on the type of the object (*note
     Forms::.).
     Since `eval' is a function, the argument expression that appears
     in a call to `eval' is evaluated twice: once as preparation before
     `eval' is called, and again by the `eval' function itself.  Here
     is an example:
          (setq foo 'bar)
               => bar
          (setq bar 'baz)
               => baz
          ;; `eval' receives argument `bar', which is the value of `foo'
          (eval foo)
               => baz
          (eval 'foo)
               => bar
     The number of currently active calls to `eval' is limited to
     `max-lisp-eval-depth' (see below).
 - Command: eval-region START END &optional STREAM
     This function evaluates the forms in the current buffer in the
     region defined by the positions START and END.  It reads forms from
     the region and calls `eval' on them until the end of the region is
     reached, or until an error is signaled and not handled.
     If STREAM is supplied, `standard-output' is bound to it during the
     evaluation.
     You can use the variable `load-read-function' to specify a function
     for `eval-region' to use instead of `read' for reading
     expressions.  *Note How Programs Do Loading::.
     `eval-region' always returns `nil'.
 - Command: eval-current-buffer &optional STREAM
     This is like `eval-region' except that it operates on the whole
     buffer.
 - Variable: max-lisp-eval-depth
     This variable defines the maximum depth allowed in calls to `eval',
     `apply', and `funcall' before an error is signaled (with error
     message `"Lisp nesting exceeds max-lisp-eval-depth"').  This counts
     internal uses of those functions, such as for calling the functions
     mentioned in Lisp expressions, and recursive evaluation of
     function call arguments and function body forms.
     This limit, with the associated error when it is exceeded, is one
     way that Lisp avoids infinite recursion on an ill-defined function.
     The default value of this variable is 200.  If you set it to a
     value less than 100, Lisp will reset it to 100 if the given value
     is reached.
     `max-specpdl-size' provides another limit on nesting.  *Note Local
     Variables::.
 - Variable: values
     The value of this variable is a list of the values returned by all
     the expressions that were read from buffers (including the
     minibuffer), evaluated, and printed.  The elements are ordered
     most recent first.
          (setq x 1)
               => 1
          (list 'A (1+ 2) auto-save-default)
               => (A 3 t)
          values
               => ((A 3 t) 1 ...)
     This variable is useful for referring back to values of forms
     recently evaluated.  It is generally a bad idea to print the value
     of `values' itself, since this may be very long.  Instead, examine
     particular elements, like this:
          ;; Refer to the most recent evaluation result.
          (nth 0 values)
               => (A 3 t)
          ;; That put a new element on,
          ;;   so all elements move back one.
          (nth 1 values)
               => (A 3 t)
          ;; This gets the element that was next-to-most-recent
          ;;   before this example.
          (nth 3 values)
               => 1
File: elisp,  Node: Forms,  Next: Quoting,  Prev: Eval,  Up: Evaluation
Kinds of Forms
==============
   A Lisp object that is intended to be evaluated is called a "form".
How Emacs evaluates a form depends on its data type.  Emacs has three
different kinds of form that are evaluated differently: symbols, lists,
and "all other types".  This section describes all three kinds,
starting with "all other types" which are self-evaluating forms.
* Menu:
* Self-Evaluating Forms::   Forms that evaluate to themselves.
* Symbol Forms::            Symbols evaluate as variables.
* Classifying Lists::       How to distinguish various sorts of list forms.
* Function Indirection::    When a symbol appears as the car of a list,
                  we find the real function via the symbol.
* Function Forms::          Forms that call functions.
* Macro Forms::             Forms that call macros.
* Special Forms::           "Special forms" are idiosyncratic primitives,
                              most of them extremely important.
* Autoloading::             Functions set up to load files
                              containing their real definitions.
File: elisp,  Node: Self-Evaluating Forms,  Next: Symbol Forms,  Up: Forms
Self-Evaluating Forms
---------------------
   A "self-evaluating form" is any form that is not a list or symbol.
Self-evaluating forms evaluate to themselves: the result of evaluation
is the same object that was evaluated.  Thus, the number 25 evaluates to
25, and the string `"foo"' evaluates to the string `"foo"'.  Likewise,
evaluation of a vector does not cause evaluation of the elements of the
vector--it returns the same vector with its contents unchanged.
     '123               ; An object, shown without evaluation.
          => 123
     123                ; Evaluated as usual---result is the same.
          => 123
     (eval '123)        ; Evaluated ``by hand''---result is the same.
          => 123
     (eval (eval '123)) ; Evaluating twice changes nothing.
          => 123
   It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
syntax, because there's no way to write them textually.  It is possible
to construct Lisp expressions containing these types by means of a Lisp
program.  Here is an example:
     ;; Build an expression containing a buffer object.
     (setq buffer (list 'print (current-buffer)))
          => (print #<buffer eval.texi>)
     ;; Evaluate it.
     (eval buffer)
          -| #<buffer eval.texi>
          => #<buffer eval.texi>
File: elisp,  Node: Symbol Forms,  Next: Classifying Lists,  Prev: Self-Evaluating Forms,  Up: Forms
Symbol Forms
------------
   When a symbol is evaluated, it is treated as a variable.  The result
is the variable's value, if it has one.  If it has none (if its value
cell is void), an error is signaled.  For more information on the use of
variables, see *Note Variables::.
   In the following example, we set the value of a symbol with `setq'.
Then we evaluate the symbol, and get back the value that `setq' stored.
     (setq a 123)
          => 123
     (eval 'a)
          => 123
     a
          => 123
   The symbols `nil' and `t' are treated specially, so that the value
of `nil' is always `nil', and the value of `t' is always `t'; you
cannot set or bind them to any other values.  Thus, these two symbols
act like self-evaluating forms, even though `eval' treats them like any
other symbol.
File: elisp,  Node: Classifying Lists,  Next: Function Indirection,  Prev: Symbol Forms,  Up: Forms
Classification of List Forms
----------------------------
   A form that is a nonempty list is either a function call, a macro
call, or a special form, according to its first element.  These three
kinds of forms are evaluated in different ways, described below.  The
remaining list elements constitute the "arguments" for the function,
macro, or special form.
   The first step in evaluating a nonempty list is to examine its first
element.  This element alone determines what kind of form the list is
and how the rest of the list is to be processed.  The first element is
*not* evaluated, as it would be in some Lisp dialects such as Scheme.
File: elisp,  Node: Function Indirection,  Next: Function Forms,  Prev: Classifying Lists,  Up: Forms
Symbol Function Indirection
---------------------------
   If the first element of the list is a symbol then evaluation examines
the symbol's function cell, and uses its contents instead of the
original symbol.  If the contents are another symbol, this process,
called "symbol function indirection", is repeated until it obtains a
non-symbol.  *Note Function Names::, for more information about using a
symbol as a name for a function stored in the function cell of the
symbol.
   One possible consequence of this process is an infinite loop, in the
event that a symbol's function cell refers to the same symbol.  Or a
symbol may have a void function cell, in which case the subroutine
`symbol-function' signals a `void-function' error.  But if neither of
these things happens, we eventually obtain a non-symbol, which ought to
be a function or other suitable object.
   More precisely, we should now have a Lisp function (a lambda
expression), a byte-code function, a primitive function, a Lisp macro, a
special form, or an autoload object.  Each of these types is a case
described in one of the following sections.  If the object is not one of
these types, the error `invalid-function' is signaled.
   The following example illustrates the symbol indirection process.  We
use `fset' to set the function cell of a symbol and `symbol-function'
to get the function cell contents (*note Function Cells::.).
Specifically, we store the symbol `car' into the function cell of
`first', and the symbol `first' into the function cell of `erste'.
     ;; Build this function cell linkage:
     ;;   -------------       -----        -------        -------
     ;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
     ;;   -------------       -----        -------        -------
     (symbol-function 'car)
          => #<subr car>
     (fset 'first 'car)
          => car
     (fset 'erste 'first)
          => first
     (erste '(1 2 3))   ; Call the function referenced by `erste'.
          => 1
   By contrast, the following example calls a function without any
symbol function indirection, because the first element is an anonymous
Lisp function, not a symbol.
     ((lambda (arg) (erste arg))
      '(1 2 3))
          => 1
Executing the function itself evaluates its body; this does involve
symbol function indirection when calling `erste'.
   The built-in function `indirect-function' provides an easy way to
perform symbol function indirection explicitly.
 - Function: indirect-function FUNCTION
     This function returns the meaning of FUNCTION as a function.  If
     FUNCTION is a symbol, then it finds FUNCTION's function definition
     and starts over with that value.  If FUNCTION is not a symbol,
     then it returns FUNCTION itself.
     Here is how you could define `indirect-function' in Lisp:
          (defun indirect-function (function)
            (if (symbolp function)
                (indirect-function (symbol-function function))
              function))
File: elisp,  Node: Function Forms,  Next: Macro Forms,  Prev: Function Indirection,  Up: Forms
Evaluation of Function Forms
----------------------------
   If the first element of a list being evaluated is a Lisp function
object, byte-code object or primitive function object, then that list is
a "function call".  For example, here is a call to the function `+':
     (+ 1 x)
   The first step in evaluating a function call is to evaluate the
remaining elements of the list from left to right.  The results are the
actual argument values, one value for each list element.  The next step
is to call the function with this list of arguments, effectively using
the function `apply' (*note Calling Functions::.).  If the function is
written in Lisp, the arguments are used to bind the argument variables
of the function (*note Lambda Expressions::.); then the forms in the
function body are evaluated in order, and the value of the last body
form becomes the value of the function call.
File: elisp,  Node: Macro Forms,  Next: Special Forms,  Prev: Function Forms,  Up: Forms
Lisp Macro Evaluation
---------------------
   If the first element of a list being evaluated is a macro object,
then the list is a "macro call".  When a macro call is evaluated, the
elements of the rest of the list are *not* initially evaluated.
Instead, these elements themselves are used as the arguments of the
macro.  The macro definition computes a replacement form, called the
"expansion" of the macro, to be evaluated in place of the original
form.  The expansion may be any sort of form: a self-evaluating
constant, a symbol, or a list.  If the expansion is itself a macro call,
this process of expansion repeats until some other sort of form results.
   Ordinary evaluation of a macro call finishes by evaluating the
expansion.  However, the macro expansion is not necessarily evaluated
right away, or at all, because other programs also expand macro calls,
and they may or may not evaluate the expansions.
   Normally, the argument expressions are not evaluated as part of
computing the macro expansion, but instead appear as part of the
expansion, so they are computed when the expansion is computed.
   For example, given a macro defined as follows:
     (defmacro cadr (x)
       (list 'car (list 'cdr x)))
an expression such as `(cadr (assq 'handler list))' is a macro call,
and its expansion is:
     (car (cdr (assq 'handler list)))
Note that the argument `(assq 'handler list)' appears in the expansion.
   *Note Macros::, for a complete description of Emacs Lisp macros.
File: elisp,  Node: Special Forms,  Next: Autoloading,  Prev: Macro Forms,  Up: Forms
Special Forms
-------------
   A "special form" is a primitive function specially marked so that
its arguments are not all evaluated.  Most special forms define control
structures or perform variable bindings--things which functions cannot
   Each special form has its own rules for which arguments are evaluated
and which are used without evaluation.  Whether a particular argument is
evaluated may depend on the results of evaluating other arguments.
   Here is a list, in alphabetical order, of all of the special forms in
Emacs Lisp with a reference to where each is described.
`and'
     *note Combining Conditions::.
`catch'
     *note Catch and Throw::.
`cond'
     *note Conditionals::.
`condition-case'
     *note Handling Errors::.
`defconst'
     *note Defining Variables::.
`defmacro'
     *note Defining Macros::.
`defun'
     *note Defining Functions::.
`defvar'
     *note Defining Variables::.
`function'
     *note Anonymous Functions::.
     *note Conditionals::.
`interactive'
     *note Interactive Call::.
`let'
`let*'
     *note Local Variables::.
     *note Combining Conditions::.
`prog1'
`prog2'
`progn'
     *note Sequencing::.
`quote'
     *note Quoting::.
`save-excursion'
     *note Excursions::.
`save-restriction'
     *note Narrowing::.
`save-window-excursion'
     *note Window Configurations::.
`setq'
     *note Setting Variables::.
`setq-default'
     *note Creating Buffer-Local::.
`track-mouse'
     *note Mouse Tracking::.
`unwind-protect'
     *note Nonlocal Exits::.
`while'
     *note Iteration::.
`with-output-to-temp-buffer'
     *note Temporary Displays::.
     Common Lisp note: Here are some comparisons of special forms in
     GNU Emacs Lisp and Common Lisp.  `setq', `if', and `catch' are
     special forms in both Emacs Lisp and Common Lisp.  `defun' is a
     special form in Emacs Lisp, but a macro in Common Lisp.
     `save-excursion' is a special form in Emacs Lisp, but doesn't
     exist in Common Lisp.  `throw' is a special form in Common Lisp
     (because it must be able to throw multiple values), but it is a
     function in Emacs Lisp (which doesn't have multiple values).
File: elisp,  Node: Autoloading,  Prev: Special Forms,  Up: Forms
Autoloading
-----------
   The "autoload" feature allows you to call a function or macro whose
function definition has not yet been loaded into Emacs.  It specifies
which file contains the definition.  When an autoload object appears as
a symbol's function definition, calling that symbol as a function
automatically loads the specified file; then it calls the real
definition loaded from that file.  *Note Autoload::.
File: elisp,  Node: Quoting,  Prev: Forms,  Up: Evaluation
Quoting
=======
   The special form `quote' returns its single argument, as written,
without evaluating it.  This provides a way to include constant symbols
and lists, which are not self-evaluating objects, in a program.  (It is
not necessary to quote self-evaluating objects such as numbers, strings,
and vectors.)
 - Special Form: quote OBJECT
     This special form returns OBJECT, without evaluating it.
   Because `quote' is used so often in programs, Lisp provides a
convenient read syntax for it.  An apostrophe character (`'') followed
by a Lisp object (in read syntax) expands to a list whose first element
is `quote', and whose second element is the object.  Thus, the read
syntax `'x' is an abbreviation for `(quote x)'.
   Here are some examples of expressions that use `quote':
     (quote (+ 1 2))
          => (+ 1 2)
     (quote foo)
          => foo
     'foo
          => foo
     ''foo
          => (quote foo)
     '(quote foo)
          => (quote foo)
     ['foo]
          => [(quote foo)]
   Other quoting constructs include `function' (*note Anonymous
Functions::.), which causes an anonymous lambda expression written in
Lisp to be compiled, and ``' (*note Backquote::.), which is used to
quote only part of a list, while computing and substituting other parts.
File: elisp,  Node: Control Structures,  Next: Variables,  Prev: Evaluation,  Up: Top
Control Structures
******************
   A Lisp program consists of expressions or "forms" (*note Forms::.).
We control the order of execution of the forms by enclosing them in
"control structures".  Control structures are special forms which
control when, whether, or how many times to execute the forms they
contain.
   The simplest order of execution is sequential execution: first form
A, then form B, and so on.  This is what happens when you write several
forms in succession in the body of a function, or at top level in a
file of Lisp code--the forms are executed in the order written.  We
call this "textual order".  For example, if a function body consists of
two forms A and B, evaluation of the function evaluates first A and
then B, and the function's value is the value of B.
   Explicit control structures make possible an order of execution other
than sequential.
   Emacs Lisp provides several kinds of control structure, including
other varieties of sequencing, conditionals, iteration, and (controlled)
jumps--all discussed below.  The built-in control structures are
special forms since their subforms are not necessarily evaluated or not
evaluated sequentially.  You can use macros to define your own control
structure constructs (*note Macros::.).
* Menu:
* Sequencing::             Evaluation in textual order.
* Conditionals::           `if', `cond'.
* Combining Conditions::   `and', `or', `not'.
* Iteration::              `while' loops.
* Nonlocal Exits::         Jumping out of a sequence.
File: elisp,  Node: Sequencing,  Next: Conditionals,  Up: Control Structures
Sequencing
==========
   Evaluating forms in the order they appear is the most common way
control passes from one form to another.  In some contexts, such as in a
function body, this happens automatically.  Elsewhere you must use a
control structure construct to do this: `progn', the simplest control
construct of Lisp.
   A `progn' special form looks like this:
     (progn A B C ...)
and it says to execute the forms A, B, C and so on, in that order.
These forms are called the body of the `progn' form.  The value of the
last form in the body becomes the value of the entire `progn'.
   In the early days of Lisp, `progn' was the only way to execute two
or more forms in succession and use the value of the last of them.  But
programmers found they often needed to use a `progn' in the body of a
function, where (at that time) only one form was allowed.  So the body
of a function was made into an "implicit `progn'": several forms are
allowed just as in the body of an actual `progn'.  Many other control
structures likewise contain an implicit `progn'.  As a result, `progn'
is not used as often as it used to be.  It is needed now most often
inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
 - Special Form: progn FORMS...
     This special form evaluates all of the FORMS, in textual order,
     returning the result of the final form.
          (progn (print "The first form")
                 (print "The second form")
                 (print "The third form"))
               -| "The first form"
               -| "The second form"
               -| "The third form"
          => "The third form"
   Two other control constructs likewise evaluate a series of forms but
return a different value:
 - Special Form: prog1 FORM1 FORMS...
     This special form evaluates FORM1 and all of the FORMS, in textual
     order, returning the result of FORM1.
          (prog1 (print "The first form")
                 (print "The second form")
                 (print "The third form"))
               -| "The first form"
               -| "The second form"
               -| "The third form"
          => "The first form"
     Here is a way to remove the first element from a list in the
     variable `x', then return the value of that former element:
          (prog1 (car x) (setq x (cdr x)))
 - Special Form: prog2 FORM1 FORM2 FORMS...
     This special form evaluates FORM1, FORM2, and all of the following
     FORMS, in textual order, returning the result of FORM2.
          (prog2 (print "The first form")
                 (print "The second form")
                 (print "The third form"))
               -| "The first form"
               -| "The second form"
               -| "The third form"
          => "The second form"
File: elisp,  Node: Conditionals,  Next: Combining Conditions,  Prev: Sequencing,  Up: Control Structures
Conditionals
============
   Conditional control structures choose among alternatives.  Emacs Lisp
has two conditional forms: `if', which is much the same as in other
languages, and `cond', which is a generalized case statement.
 - Special Form: if CONDITION THEN-FORM ELSE-FORMS...
     `if' chooses between the THEN-FORM and the ELSE-FORMS based on the
     value of CONDITION.  If the evaluated CONDITION is non-`nil',
     THEN-FORM is evaluated and the result returned.  Otherwise, the
     ELSE-FORMS are evaluated in textual order, and the value of the
     last one is returned.  (The ELSE part of `if' is an example of an
     implicit `progn'.  *Note Sequencing::.)
     If CONDITION has the value `nil', and no ELSE-FORMS are given,
     `if' returns `nil'.
     `if' is a special form because the branch that is not selected is
     never evaluated--it is ignored.  Thus, in the example below,
     `true' is not printed because `print' is never called.
          (if nil
              (print 'true)
            'very-false)
          => very-false
 - Special Form: cond CLAUSE...
     `cond' chooses among an arbitrary number of alternatives.  Each
     CLAUSE in the `cond' must be a list.  The CAR of this list is the
     CONDITION; the remaining elements, if any, the BODY-FORMS.  Thus,
     a clause looks like this:
          (CONDITION BODY-FORMS...)
     `cond' tries the clauses in textual order, by evaluating the
     CONDITION of each clause.  If the value of CONDITION is non-`nil',
     the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
     the value of the last of BODY-FORMS becomes the value of the
     `cond'.  The remaining clauses are ignored.
     If the value of CONDITION is `nil', the clause "fails", so the
     `cond' moves on to the following clause, trying its CONDITION.
     If every CONDITION evaluates to `nil', so that every clause fails,
     `cond' returns `nil'.
     A clause may also look like this:
          (CONDITION)
     Then, if CONDITION is non-`nil' when tested, the value of
     CONDITION becomes the value of the `cond' form.
     The following example has four clauses, which test for the cases
     where the value of `x' is a number, string, buffer and symbol,
     respectively:
          (cond ((numberp x) x)
                ((stringp x) x)
                ((bufferp x)
                 (setq temporary-hack x) ; multiple body-forms
                 (buffer-name x))        ; in one clause
                ((symbolp x) (symbol-value x)))
     Often we want to execute the last clause whenever none of the
     previous clauses was successful.  To do this, we use `t' as the
     CONDITION of the last clause, like this: `(t BODY-FORMS)'.  The
     form `t' evaluates to `t', which is never `nil', so this clause
     never fails, provided the `cond' gets to it at all.
     For example,
          (cond ((eq a 'hack) 'foo)
                (t "default"))
          => "default"
     This expression is a `cond' which returns `foo' if the value of
     `a' is 1, and returns the string `"default"' otherwise.
   Any conditional construct can be expressed with `cond' or with `if'.
Therefore, the choice between them is a matter of style.  For example:
     (if A B C)
     ==
     (cond (A B) (t C))
File: elisp,  Node: Combining Conditions,  Next: Iteration,  Prev: Conditionals,  Up: Control Structures
Constructs for Combining Conditions
===================================
   This section describes three constructs that are often used together
with `if' and `cond' to express complicated conditions.  The constructs
`and' and `or' can also be used individually as kinds of multiple
conditional constructs.
 - Function: not CONDITION
     This function tests for the falsehood of CONDITION.  It returns
     `t' if CONDITION is `nil', and `nil' otherwise.  The function
     `not' is identical to `null', and we recommend using the name
     `null' if you are testing for an empty list.
 - Special Form: and CONDITIONS...
     The `and' special form tests whether all the CONDITIONS are true.
     It works by evaluating the CONDITIONS one by one in the order
     written.
     If any of the CONDITIONS evaluates to `nil', then the result of
     the `and' must be `nil' regardless of the remaining CONDITIONS; so
     `and' returns right away, ignoring the remaining CONDITIONS.
     If all the CONDITIONS turn out non-`nil', then the value of the
     last of them becomes the value of the `and' form.
     Here is an example.  The first condition returns the integer 1,
     which is not `nil'.  Similarly, the second condition returns the
     integer 2, which is not `nil'.  The third condition is `nil', so
     the remaining condition is never evaluated.
          (and (print 1) (print 2) nil (print 3))
               -| 1
               -| 2
          => nil
     Here is a more realistic example of using `and':
          (if (and (consp foo) (eq (car foo) 'x))
              (message "foo is a list starting with x"))
     Note that `(car foo)' is not executed if `(consp foo)' returns
     `nil', thus avoiding an error.
     `and' can be expressed in terms of either `if' or `cond'.  For
     example:
          (and ARG1 ARG2 ARG3)
          ==
          (if ARG1 (if ARG2 ARG3))
          ==
          (cond (ARG1 (cond (ARG2 ARG3))))
 - Special Form: or CONDITIONS...
     The `or' special form tests whether at least one of the CONDITIONS
     is true.  It works by evaluating all the CONDITIONS one by one in
     the order written.
     If any of the CONDITIONS evaluates to a non-`nil' value, then the
     result of the `or' must be non-`nil'; so `or' returns right away,
     ignoring the remaining CONDITIONS.  The value it returns is the
     non-`nil' value of the condition just evaluated.
     If all the CONDITIONS turn out `nil', then the `or' expression
     returns `nil'.
     For example, this expression tests whether `x' is either 0 or
     `nil':
          (or (eq x nil) (eq x 0))
     Like the `and' construct, `or' can be written in terms of `cond'.
     For example:
          (or ARG1 ARG2 ARG3)
          ==
          (cond (ARG1)
                (ARG2)
                (ARG3))
     You could almost write `or' in terms of `if', but not quite:
          (if ARG1 ARG1
            (if ARG2 ARG2
              ARG3))
     This is not completely equivalent because it can evaluate ARG1 or
     ARG2 twice.  By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
     any argument more than once.
File: elisp,  Node: Iteration,  Next: Nonlocal Exits,  Prev: Combining Conditions,  Up: Control Structures
Iteration
=========
   Iteration means executing part of a program repetitively.  For
example, you might want to repeat some computation once for each element
of a list, or once for each integer from 0 to N.  You can do this in
Emacs Lisp with the special form `while':
 - Special Form: while CONDITION FORMS...
     `while' first evaluates CONDITION.  If the result is non-`nil', it
     evaluates FORMS in textual order.  Then it reevaluates CONDITION,
     and if the result is non-`nil', it evaluates FORMS again.  This
     process repeats until CONDITION evaluates to `nil'.
     There is no limit on the number of iterations that may occur.  The
     loop will continue until either CONDITION evaluates to `nil' or
     until an error or `throw' jumps out of it (*note Nonlocal
     Exits::.).
     The value of a `while' form is always `nil'.
          (setq num 0)
               => 0
          (while (< num 4)
            (princ (format "Iteration %d." num))
            (setq num (1+ num)))
               -| Iteration 0.
               -| Iteration 1.
               -| Iteration 2.
               -| Iteration 3.
               => nil
     If you would like to execute something on each iteration before the
     end-test, put it together with the end-test in a `progn' as the
     first argument of `while', as shown here:
          (while (progn
                   (forward-line 1)
                   (not (looking-at "^$"))))
     This moves forward one line and continues moving by lines until it
     reaches an empty.  It is unusual in that the `while' has no body,
     just the end test (which also does the real work of moving point).
File: elisp,  Node: Nonlocal Exits,  Prev: Iteration,  Up: Control Structures
Nonlocal Exits
==============
   A "nonlocal exit" is a transfer of control from one point in a
program to another remote point.  Nonlocal exits can occur in Emacs Lisp
as a result of errors; you can also use them under explicit control.
Nonlocal exits unbind all variable bindings made by the constructs being
exited.
* Menu:
* Catch and Throw::     Nonlocal exits for the program's own purposes.
* Examples of Catch::   Showing how such nonlocal exits can be written.
* Errors::              How errors are signaled and handled.
* Cleanups::            Arranging to run a cleanup form if an error happens.
File: elisp,  Node: Catch and Throw,  Next: Examples of Catch,  Up: Nonlocal Exits
Explicit Nonlocal Exits: `catch' and `throw'
--------------------------------------------
   Most control constructs affect only the flow of control within the
construct itself.  The function `throw' is the exception to this rule
of normal program execution: it performs a nonlocal exit on request.
(There are other exceptions, but they are for error handling only.)
`throw' is used inside a `catch', and jumps back to that `catch'.  For
example:
     (catch 'foo
       (progn
         ...
         (throw 'foo t)
         ...))
The `throw' transfers control straight back to the corresponding
`catch', which returns immediately.  The code following the `throw' is
not executed.  The second argument of `throw' is used as the return
value of the `catch'.
   The `throw' and the `catch' are matched through the first argument:
`throw' searches for a `catch' whose first argument is `eq' to the one
specified.  Thus, in the above example, the `throw' specifies `foo',
and the `catch' specifies the same symbol, so that `catch' is
applicable.  If there is more than one applicable `catch', the
innermost one takes precedence.
   Executing `throw' exits all Lisp constructs up to the matching
`catch', including function calls.  When binding constructs such as
`let' or function calls are exited in this way, the bindings are
unbound, just as they are when these constructs exit normally (*note
Local Variables::.).  Likewise, `throw' restores the buffer and
position saved by `save-excursion' (*note Excursions::.), and the
narrowing status saved by `save-restriction' and the window selection
saved by `save-window-excursion' (*note Window Configurations::.).  It
also runs any cleanups established with the `unwind-protect' special
form when it exits that form (*note Cleanups::.).
   The `throw' need not appear lexically within the `catch' that it
jumps to.  It can equally well be called from another function called
within the `catch'.  As long as the `throw' takes place chronologically
after entry to the `catch', and chronologically before exit from it, it
has access to that `catch'.  This is why `throw' can be used in
commands such as `exit-recursive-edit' that throw back to the editor
command loop (*note Recursive Editing::.).
     Common Lisp note: Most other versions of Lisp, including Common
     Lisp, have several ways of transferring control nonsequentially:
     `return', `return-from', and `go', for example.  Emacs Lisp has
     only `throw'.
 - Special Form: catch TAG BODY...
     `catch' establishes a return point for the `throw' function.  The
     return point is distinguished from other such return points by TAG,
     which may be any Lisp object.  The argument TAG is evaluated
     normally before the return point is established.
     With the return point in effect, `catch' evaluates the forms of the
     BODY in textual order.  If the forms execute normally, without
     error or nonlocal exit, the value of the last body form is
     returned from the `catch'.
     If a `throw' is done within BODY specifying the same value TAG,
     the `catch' exits immediately; the value it returns is whatever
     was specified as the second argument of `throw'.
 - Function: throw TAG VALUE
     The purpose of `throw' is to return from a return point previously
     established with `catch'.  The argument TAG is used to choose
     among the various existing return points; it must be `eq' to the
     value specified in the `catch'.  If multiple return points match
     TAG, the innermost one is used.
     The argument VALUE is used as the value to return from that
     `catch'.
     If no return point is in effect with tag TAG, then a `no-catch'
     error is signaled with data `(TAG VALUE)'.
File: elisp,  Node: Examples of Catch,  Next: Errors,  Prev: Catch and Throw,  Up: Nonlocal Exits
Examples of `catch' and `throw'
-------------------------------
   One way to use `catch' and `throw' is to exit from a doubly nested
loop.  (In most languages, this would be done with a "go to".) Here we
compute `(foo I J)' for I and J varying from 0 to 9:
     (defun search-foo ()
       (catch 'loop
         (let ((i 0))
           (while (< i 10)
             (let ((j 0))
               (while (< j 10)
                 (if (foo i j)
                     (throw 'loop (list i j)))
                 (setq j (1+ j))))
             (setq i (1+ i))))))
If `foo' ever returns non-`nil', we stop immediately and return a list
of I and J.  If `foo' always returns `nil', the `catch' returns
normally, and the value is `nil', since that is the result of the
`while'.
   Here are two tricky examples, slightly different, showing two return
points at once.  First, two return points with the same tag, `hack':
     (defun catch2 (tag)
       (catch tag
         (throw 'hack 'yes)))
     => catch2

     (catch 'hack
       (print (catch2 'hack))
       'no)
     -| yes
     => no
Since both return points have tags that match the `throw', it goes to
the inner one, the one established in `catch2'.  Therefore, `catch2'
returns normally with value `yes', and this value is printed.  Finally
the second body form in the outer `catch', which is `'no', is evaluated
and returned from the outer `catch'.
   Now let's change the argument given to `catch2':
     (defun catch2 (tag)
       (catch tag
         (throw 'hack 'yes)))
     => catch2

     (catch 'hack
       (print (catch2 'quux))
       'no)
     => yes
We still have two return points, but this time only the outer one has
the tag `hack'; the inner one has the tag `quux' instead.  Therefore,
`throw' makes the outer `catch' return the value `yes'.  The function
`print' is never called, and the body-form `'no' is never evaluated.
File: elisp,  Node: Errors,  Next: Cleanups,  Prev: Examples of Catch,  Up: Nonlocal Exits
Errors
------
   When Emacs Lisp attempts to evaluate a form that, for some reason,
cannot be evaluated, it "signals" an "error".
   When an error is signaled, Emacs's default reaction is to print an
error message and terminate execution of the current command.  This is
the right thing to do in most cases, such as if you type `C-f' at the
end of the buffer.
   In complicated programs, simple termination may not be what you want.
For example, the program may have made temporary changes in data
structures, or created temporary buffers that should be deleted before
the program is finished.  In such cases, you would use `unwind-protect'
to establish "cleanup expressions" to be evaluated in case of error.
(*Note Cleanups::.)  Occasionally, you may wish the program to continue
execution despite an error in a subroutine.  In these cases, you would
use `condition-case' to establish "error handlers" to recover control
in case of error.
   Resist the temptation to use error handling to transfer control from
one part of the program to another; use `catch' and `throw' instead.
*Note Catch and Throw::.
* Menu:
* Signaling Errors::      How to report an error.
* Processing of Errors::  What Emacs does when you report an error.
* Handling Errors::       How you can trap errors and continue execution.
* Error Symbols::         How errors are classified for trapping them.
File: elisp,  Node: Signaling Errors,  Next: Processing of Errors,  Up: Errors
How to Signal an Error
......................
   Most errors are signaled "automatically" within Lisp primitives
which you call for other purposes, such as if you try to take the CAR
of an integer or move forward a character at the end of the buffer; you
can also signal errors explicitly with the functions `error' and
`signal'.
   Quitting, which happens when the user types `C-g', is not considered
an error, but it is handled almost like an error.  *Note Quitting::.
 - Function: error FORMAT-STRING &rest ARGS
     This function signals an error with an error message constructed by
     applying `format' (*note String Conversion::.) to FORMAT-STRING
     and ARGS.
     These examples show typical uses of `error':
          (error "You have committed an error.
                  Try something else.")
               error--> You have committed an error.
                  Try something else.

          (error "You have committed %d errors." 10)
               error--> You have committed 10 errors.
     `error' works by calling `signal' with two arguments: the error
     symbol `error', and a list containing the string returned by
     `format'.
     If you want to use your own string as an error message verbatim,
     don't just write `(error STRING)'.  If STRING contains `%', it
     will be interpreted as a format specifier, with undesirable
     results.  Instead, use `(error "%s" STRING)'.
 - Function: signal ERROR-SYMBOL DATA
     This function signals an error named by ERROR-SYMBOL.  The
     argument DATA is a list of additional Lisp objects relevant to the
     circumstances of the error.
     The argument ERROR-SYMBOL must be an "error symbol"--a symbol
     bearing a property `error-conditions' whose value is a list of
     condition names.  This is how Emacs Lisp classifies different
     sorts of errors.
     The number and significance of the objects in DATA depends on
     ERROR-SYMBOL.  For example, with a `wrong-type-arg' error, there
     are two objects in the list: a predicate that describes the type
     that was expected, and the object that failed to fit that type.
     *Note Error Symbols::, for a description of error symbols.
     Both ERROR-SYMBOL and DATA are available to any error handlers
     that handle the error: `condition-case' binds a local variable to
     a list of the form `(ERROR-SYMBOL .  DATA)' (*note Handling
     Errors::.).  If the error is not handled, these two values are
     used in printing the error message.
     The function `signal' never returns (though in older Emacs versions
     it could sometimes return).
          (signal 'wrong-number-of-arguments '(x y))
               error--> Wrong number of arguments: x, y
          (signal 'no-such-error '("My unknown error condition."))
               error--> peculiar error: "My unknown error condition."
     Common Lisp note: Emacs Lisp has nothing like the Common Lisp
     concept of continuable errors.
File: elisp,  Node: Processing of Errors,  Next: Handling Errors,  Prev: Signaling Errors,  Up: Errors
How Emacs Processes Errors
..........................
   When an error is signaled, `signal' searches for an active "handler"
for the error.  A handler is a sequence of Lisp expressions designated
to be executed if an error happens in part of the Lisp program.  If the
error has an applicable handler, the handler is executed, and control
resumes following the handler.  The handler executes in the environment
of the `condition-case' that established it; all functions called
within that `condition-case' have already been exited, and the handler
cannot return to them.
   If there is no applicable handler for the error, the current command
is terminated and control returns to the editor command loop, because
the command loop has an implicit handler for all kinds of errors.  The
command loop's handler uses the error symbol and associated data to
print an error message.
   An error that has no explicit handler may call the Lisp debugger.
The debugger is enabled if the variable `debug-on-error' (*note Error
Debugging::.) is non-`nil'.  Unlike error handlers, the debugger runs
in the environment of the error, so that you can examine values of
variables precisely as they were at the time of the error.